home *** CD-ROM | disk | FTP | other *** search
/ Amiga Developer CD 2.1 / Amiga Developer CD v2.1.iso / Reference / DevCon / Atlanta_1990 / Atlanta-Devcon.2 / AppShell / Doc / appshell.doc
Encoding:
Text File  |  1992-08-26  |  39.8 KB  |  1,647 lines
  1. TABLE OF CONTENTS
  2.  
  3.  
  4. Standard AppShell Application Functions
  5.  
  6. appshell.library/ACTIVATE
  7. appshell.library/ALIAS
  8. appshell.library/CMDSHELL
  9. appshell.library/DISABLE
  10. appshell.library/ENABLE
  11. appshell.library/HOTKEY
  12. appshell.library/RX
  13. appshell.library/TOBACK
  14. appshell.library/TOFRONT
  15. appshell.library/VERSION
  16. appshell.library/WHY
  17. appshell.library/WINDOW
  18.  
  19.  
  20. AppShell Link Library Functions
  21.  
  22. appshell.lib/HandleApp
  23. appshell.lib/NotifyUser
  24. appshell.library/AddFuncEntries
  25. appshell.library/AddFuncEntry
  26. appshell.library/AddProjects
  27. appshell.library/APSHClearPointer
  28. appshell.library/APSHGetGadgetInfo
  29. appshell.library/APSHGetWindowInfo
  30. appshell.library/APSHSetWaitPointer
  31. appshell.library/BuildParseLine
  32. appshell.library/FindType
  33. appshell.library/FreeParseLine
  34. appshell.library/FreeProject
  35. appshell.library/FreeProjects
  36. appshell.library/GetFuncEntry
  37. appshell.library/GetFuncID
  38. appshell.library/GetFuncName
  39. appshell.library/GetProjNode
  40. appshell.library/GetText
  41. appshell.library/HandleAppAsync
  42. appshell.library/HandlerData
  43. appshell.library/HandlerFunc
  44. appshell.library/IconFromWBArg
  45. appshell.library/MatchValue
  46. appshell.library/NewProject
  47. appshell.library/ParseLine
  48. appshell.library/PerfFunc
  49. appshell.library/PrepText
  50. appshell.library/QStrCmpI
  51. appshell.library/RemoveMsgPort
  52. appshell.library/RemoveProject
  53. appshell.library/SwapProjNodes
  54. appshell.library/ACTIVATE                       appshell.library/ACTIVATE
  55.  
  56.    NAME
  57.     ACTIVATE - Activate an AppShell window.
  58.  
  59.    SYNOPSIS
  60.     ActivateID    Function ID
  61.     ActivateFunc    Function prototype
  62.  
  63.    FUNCTION
  64.     Provides a mechanism to activate an AppShell window.  Activation
  65.     involves bring the screen to front, opening the window if it is
  66.     hidden, bringing the window to front and unzooming the window if it
  67.     is zoomed.
  68.  
  69.     As a string command line:
  70.  
  71.         ACTIVATE [name]
  72.  
  73.         where [name] is a valid window name, defaults to MAIN.
  74.  
  75.     As a TagItem attribute list:
  76.  
  77.         APSH_NameTag, <name>
  78.         where <name> is a valid window name.
  79.  
  80.         APSH_WinPointer, <pointer>
  81.         where <pointer> points to a valid window structure.
  82.  
  83.     This function is implemented by the IDCMP message handler.
  84.  
  85.    SEE ALSO
  86.     TOBACK, TOFRONT, WINDOW
  87.  
  88. appshell.library/ALIAS                             appshell.library/ALIAS
  89.  
  90.    NAME
  91.     ALIAS - Used to build new commands from existing commands.
  92.  
  93.    SYNOPSIS
  94.     AliasID        Function ID
  95.     AliasFunc    Function prototype
  96.  
  97.    FUNCTION
  98.     This command is used to build new commands from existing commands
  99.     in the function table.
  100.  
  101.     As a string command line:
  102.  
  103.         ALIAS <new> <existing> [parameters]
  104.  
  105.         where <new> is the new command to add to the function
  106.         table.
  107.  
  108.         where <existing> is an existing command in the function
  109.         table to assign to the new command.
  110.  
  111.         where [parameters] are optional parameters for <existing>
  112.         to assign to <new>.
  113.  
  114.    EXAMPLE
  115.  
  116.     The following command line would assign the command OPEN to the
  117.     new command name README, and would use READ.ME as the parameter
  118.     to pass.
  119.  
  120.         ALIAS README OPEN READ.ME
  121.  
  122.    BUGS
  123.     No tags are implemented.
  124.  
  125. appshell.library/CMDSHELL                       appshell.library/CMDSHELL
  126.  
  127.    NAME
  128.     CMDSHELL - Open/Close the application command shell.
  129.  
  130.    SYNOPSIS
  131.     CMDShellID    Function ID
  132.     CMDShellFunc    Function prototype
  133.  
  134.    FUNCTION
  135.     Opens a console window whereby the user can interact directly with
  136.     the application at a command level.  Allows the user quick access
  137.     to functions or macros that they may use so infrequently that they
  138.     don't wish to bind them to a key, menu or button.
  139.  
  140.     As a string command line:
  141.  
  142.         CMDSHELL [command]
  143.         where [command] is a valid command, defaults to OPEN.
  144.  
  145.             OPEN    Open the command shell.
  146.  
  147.     As a TagItem attribute list:
  148.  
  149.         APSH_Command, <command>
  150.         where <command> is a valid command, defaults to MH_OPEN.
  151.  
  152.             MH_OPEN    Open the command shell.
  153.  
  154.     This function is implemented by the DOS message handler.
  155.  
  156. appshell.library/DISABLE                         appshell.library/DISABLE
  157.  
  158.    NAME
  159.     DISABLE - Disable a function and its interfaces.
  160.  
  161.    SYNOPSIS
  162.     DisableID    Function ID
  163.     DisableFunc    Function prototype
  164.  
  165.    FUNCTION
  166.     This function allows an application or user to disable a function.
  167.  
  168.     If the function is attached to a gadget or menu item, then that item
  169.     is also disabled.
  170.  
  171.     As a string command line:
  172.  
  173.         DISABLE [name]
  174.  
  175.         where [name] is a valid function name.
  176.  
  177.     As a TagItem attribute list:
  178.  
  179.         APSH_NameTag, <name>
  180.         where <name> is a valid function name.
  181.  
  182.    SEE ALSO
  183.     ENABLE
  184.  
  185. appshell.library/ENABLE                           appshell.library/ENABLE
  186.  
  187.    NAME
  188.     ENABLE - Enable a function and its interfaces.
  189.  
  190.    SYNOPSIS
  191.     EnableID    Function ID
  192.     EnableFunc    Function prototype
  193.  
  194.    FUNCTION
  195.     This function allows an application or user to enable a function.
  196.  
  197.     If the function is attached to a gadget or menu item, then that item
  198.     is also enabled.
  199.  
  200.     As a string command line:
  201.  
  202.         ENABLE [name]
  203.  
  204.         where [name] is a valid function name.
  205.  
  206.     As a TagItem attribute list:
  207.  
  208.         APSH_NameTag, <name>
  209.         where <name> is a valid function name.
  210.  
  211.    SEE ALSO
  212.     DISABLE
  213.  
  214. appshell.library/HOTKEY                           appshell.library/HOTKEY
  215.  
  216.    NAME
  217.     HOTKEY - Bind a keyboard command to a function.
  218.  
  219.    SYNOPSIS
  220.     HotKeyID    Function ID
  221.     HotKeyFunc    Function prototype
  222.  
  223.    FUNCTION
  224.     Provides a mechanism to bind a function to a keystroke or sequence
  225.     of keystrokes.
  226.  
  227.     As a string command line:
  228.  
  229.         HOTKEY <key> <function name>
  230.  
  231.         where <key> is the keystroke.
  232.  
  233.         where <function name> is a valid function name.
  234.  
  235.     As a TagItem attribute list:
  236.  
  237.  
  238.         APSH_CmdData, <key>
  239.         where <key> is the keystroke.
  240.  
  241.         APSH_NameTag, <function name>
  242.         where <function name> is a valid function name.
  243.  
  244.     This function is implemented by the IDCMP message handler.
  245.  
  246.    BUGS
  247.     Currently doesn't support anything but single, shifted and unshifted,
  248.     alphabetic characters [when called from the command line].
  249.  
  250. appshell.library/RX                                   appshell.library/RX
  251.  
  252.    NAME
  253.     RX - Pass a command through ARexx.
  254.  
  255.    SYNOPSIS
  256.     RXID        Function ID
  257.     RXFunc        Function prototype
  258.  
  259.    FUNCTION
  260.     Allows access to ARexx functions that may have otherwise been
  261.     rerouted by the application.  Should only be used if there are name
  262.     conflicts between an application function and an ARexx function.
  263.  
  264.     As a string command line:
  265.  
  266.         RX [command]
  267.  
  268.         where [command] is a command line to pass to ARexx.
  269.  
  270.     As a TagItem attribute list:
  271.  
  272.         APSH_CmdString, <command>
  273.         where <command> is a command line to pass to ARexx.
  274.  
  275.     This function is implemented by the ARexx message handler.
  276.  
  277.    BUGS
  278.     Not currently implemented.
  279.  
  280. appshell.library/TOBACK                           appshell.library/TOBACK
  281.  
  282.    NAME
  283.     TOBACK - Send an AppShell window to the back.
  284.  
  285.    SYNOPSIS
  286.     ToBackID    Function ID
  287.     ToBackFunc    Function prototype
  288.  
  289.    FUNCTION
  290.     Provides a mechanism to send an AppShell window to the back of the
  291.     other windows on the same screen.
  292.  
  293.     As a string command line:
  294.  
  295.         TOBACK [name]
  296.  
  297.         where [name] is a valid window name, defaults to MAIN.
  298.  
  299.     As a TagItem attribute list:
  300.  
  301.         APSH_NameTag, <name>
  302.         where <name> is a valid window name.
  303.  
  304.         APSH_WinPointer, <pointer>
  305.         where <pointer> points to a valid window structure.
  306.  
  307.     This function is implemented by the IDCMP message handler.
  308.  
  309.    SEE ALSO
  310.     ACTIVATE, TOFRONT, WINDOW
  311.  
  312. appshell.library/TOFRONT                         appshell.library/TOFRONT
  313.  
  314.    NAME
  315.     TOFRONT - Bring an AppShell window to the front.
  316.  
  317.    SYNOPSIS
  318.     ToFrontID    Function ID
  319.     ToFrontFunc    Function prototype
  320.  
  321.    FUNCTION
  322.     Provides a mechanism to bring an AppShell window in front of the
  323.     other windows on the same screen.
  324.  
  325.     As a string command line:
  326.  
  327.         TOFRONT [name]
  328.  
  329.         where [name] is a valid window name, defaults to MAIN.
  330.  
  331.     As a TagItem attribute list:
  332.  
  333.         APSH_NameTag, <name>
  334.         where <name> is a valid window name.
  335.  
  336.         APSH_WinPointer, <pointer>
  337.         where <pointer> points to a valid window structure.
  338.  
  339.     This function is implemented by the IDCMP message handler.
  340.  
  341.    SEE ALSO
  342.     ACTIVATE, TOBACK, WINDOW
  343.  
  344. appshell.library/VERSION                         appshell.library/VERSION
  345.  
  346.    NAME
  347.     VERSION - Uses NotifyUser() to show the current version.
  348.  
  349.    SYNOPSIS
  350.     VersionID    Function ID
  351.     VersionFunc    Function prototype
  352.  
  353.    FUNCTION
  354.     Uses NotifyUser() to show the current version of the application or
  355.     the AppShell.
  356.  
  357.     As a string command line:
  358.  
  359.         VERSION [APPSHELL]
  360.  
  361.         [APPSHELL]    To display the AppShell version.  Defaults
  362.                 to showing the application version.
  363.  
  364.    BUGS
  365.     No tags are implemented.
  366.  
  367. appshell.library/WHY                                 appshell.library/WHY
  368.  
  369.    NAME
  370.     WHY - Return information on the last error.
  371.  
  372.    SYNOPSIS
  373.     WhyID        Function ID
  374.     WhyFunc        Function prototype
  375.  
  376.    FUNCTION
  377.     For scripting purpose, the primary return value of a command should
  378.     return an error level.  This limits the error return values to small
  379.     ranges (to be consistent with DOS).  Therefore, if commands use the
  380.     secondary return field to contain information on the actual error,
  381.     then this function will allow scripts to obtain information on what
  382.     the last error actually was.
  383.  
  384.     This command takes no parameters.
  385.  
  386.     This function is implemented by the ARexx message handler.
  387.  
  388.    BUGS
  389.     Not currently implemented.
  390.  
  391. appshell.library/WINDOW                           appshell.library/WINDOW
  392.  
  393.    NAME
  394.     WINDOW - Open/Close an AppShell window
  395.  
  396.    SYNOPSIS
  397.     WindowID    Function ID
  398.     WindowFunc    Function prototype
  399.  
  400.    FUNCTION
  401.     Provides a mechanism to open or close an AppShell window.
  402.  
  403.     As a string command line:
  404.  
  405.         WINDOW [action] [name]
  406.  
  407.         where [action] is an optional command, defaults to OPEN.
  408.            OPEN        To open the window.
  409.            CLOSE    To close the window.
  410.  
  411.         where [name] is a valid window name, defaults to MAIN.
  412.  
  413.     As a TagItem attribute list:
  414.  
  415.         APSH_NameTag, <name>
  416.         where <name> is a valid window name.
  417.  
  418.         APSH_WinPointer, <pointer>
  419.         where <pointer> points to a valid window structure.
  420.  
  421.         APSH_Command, <cmd>
  422.         where <cmd> is a valid command.
  423.             MH_OPEN    To open the window.
  424.             MH_CLOSE    To close the window.
  425.  
  426.     This function is implemented by the IDCMP message handler.
  427.  
  428.    SEE ALSO
  429.     ACTIVATE, TOBACK, TOFRONT
  430.  
  431. appshell.lib/HandleApp                                 appshell.lib/HandleApp
  432.  
  433.    NAME
  434.     HandleApp - startup function for AppShell application
  435.  
  436.    SYNOPSIS
  437.     results = HandleApp (argc, argv, wbm, attrs)
  438.  
  439.     BOOL results;
  440.     int argc;
  441.     char **argv;
  442.     struct WBStartup *wbm;
  443.     struct TagItem *attrs;
  444.  
  445.    FUNCTION
  446.     This function is the application entry point to the AppShell.
  447.  
  448.    EXAMPLE
  449.  
  450.     /* ... application description tags ... */
  451.  
  452.     extern struct WBStartup *WBenchMsg;
  453.  
  454.     void main(int argc, char **argv)
  455.     {
  456.         HandleApp(argc, argv, WBenchMsg, tags);
  457.     }
  458.  
  459.    INPUTS
  460.     argc    - Number of Shell arguments being passed.
  461.     argv    - Pointer to the Shell argument list
  462.     wbm    - Pointer to the Workbench startup message.
  463.     attrs    - Pointer to the application's user interface
  464.           description.
  465.  
  466.    RESULT
  467.     TRUE    - Application was able to initialize and run.
  468.  
  469.     FALSE    - Application failed.  AppShell has already informed
  470.           user of what and where the failure was.
  471.  
  472.    SEE ALSO
  473.     HandleAppAsync()
  474.  
  475. appshell.lib/NotifyUser                               appshell.lib/NotifyUser
  476.  
  477.    NAME
  478.     NotifyUser - Display a text message to the user.
  479.  
  480.    SYNOPSIS
  481.     NotifyUser (ai, msg, tl)
  482.  
  483.     struct AppInfo * ai;
  484.     STRPTR msg;
  485.     struct TagItem * tl;
  486.  
  487.    FUNCTION
  488.     This function will display a text message to the user.  Currently
  489.     uses EasyRequest (AutoRequest if OS version less than 2.0) to display
  490.     messages.
  491.  
  492.    INPUTS
  493.  
  494.     ai    - Optional pointer to the AppInfo structure for this
  495.           application.
  496.  
  497.     msg    - Pointer to message to display.  If this field is NULL, then
  498.           the text will come from the ai->ai_TextRtn field.
  499.  
  500.     tl    - Optional pointer to an array of TagItems.
  501.  
  502. appshell.library/AddFuncEntries               appshell.library/AddFuncEntries
  503.  
  504.    NAME
  505.     AddFuncEntries - Add an array of entries to the function table.
  506.  
  507.    SYNOPSIS
  508.     results = AddFuncEntries (ai, entries);
  509.  
  510.     BOOL results;
  511.     struct AppInfo *ai;
  512.     struct Funcs *entries;
  513.  
  514.    FUNCTION
  515.     This function is used to add a NULL terminated array of entries to
  516.     the application's function table.
  517.  
  518.     The function table is maintained as an Exec linked list.  The AppShell
  519.     will free all entries when the application is shutdown.
  520.  
  521.    INPUTS
  522.     ai    - Pointer to the application's AppInfo structure.
  523.     entries    - Pointer to a NULL terminated array of Funcs structures that
  524.           describes the entry to be added to the function table.
  525.  
  526.    RESULT
  527.     TRUE    - AppShell was able to add the array to the table.
  528.     FALSE    - Unable to add the array to the function table.
  529.  
  530.    SEE ALSO
  531.     AddFuncEntry()
  532.  
  533. appshell.library/AddFuncEntry                   appshell.library/AddFuncEntry
  534.  
  535.    NAME
  536.     AddFuncEntry - Add an entry to the function table
  537.  
  538.    SYNOPSIS
  539.     results = AddFuncEntry (ai, entry);
  540.  
  541.     BOOL results;
  542.     struct AppInfo *ai;
  543.     struct Funcs *entry;
  544.  
  545.    FUNCTION
  546.     This function is used to add a new entry to the application's
  547.     function table.
  548.  
  549.     The function table is maintained as an Exec linked list.  The AppShell
  550.     will free all entries when the application is shutdown.
  551.  
  552.    INPUTS
  553.     ai    - Pointer to the application's AppInfo structure.
  554.     entry    - Pointer to a Funcs structure that describes the entry
  555.           to be added to the function table.
  556.  
  557.    RESULT
  558.     TRUE    - AppShell was able to add the function to the table.
  559.     FALSE    - Unable to add the entry to the function table.
  560.  
  561.    SEE ALSO
  562.     AddFuncEntries()
  563.  
  564. appshell.library/AddProjects                     appshell.library/AddProjects
  565.  
  566.    NAME
  567.     AddProjects - Add an array of WBArgs to the project list.
  568.  
  569.    SYNOPSIS
  570.     result = AddProjects (ai, numargs, args, tl);
  571.  
  572.     BOOL result;
  573.     struct AppInfo *ai;
  574.     LONG numargs;
  575.     struct WBArg *args;
  576.     struct TagItem *tl;
  577.  
  578.    FUNCTION
  579.     Add an array of WBArgs to the given project list.  Defaults to the
  580.     main project list.
  581.  
  582.     Valid TagItems are:
  583.  
  584.         APSH_ProjInfo,<project>
  585.         Where <project> is a valid pointer to a Project structure.
  586.         Defaults to the AppInfo project structure.
  587.  
  588.    INPUTS
  589.     ai    - Pointer to the application AppInfo structure.
  590.     numargs    - Number of arguments in the array.
  591.     args    - Pointer to an array of WBArg structures.
  592.     tl    - Pointer to an optional TagItem array.
  593.  
  594. appshell.library/APSHClearPointer           appshell.library/APSHClearPointer
  595.  
  596.    NAME
  597.     APSHClearPointer - Restore the default pointer.
  598.  
  599.    SYNOPSIS
  600.     APSHClearPointer (ai, tl);
  601.  
  602.     struct AppInfo * ai;
  603.     struct TagItem * tl;
  604.  
  605.    FUNCTION
  606.     This function restores the default pointer for the specified window.
  607.     Defaults to the current window (according to AppShell).
  608.  
  609.     Valid TagItems are:
  610.  
  611.         APSH_WinName, <name>
  612.         where <name> is a valid window name.
  613.  
  614.         APSH_WinPointer, <pointer>
  615.         where <pointer> points to a valid window.
  616.  
  617.    INPUTS
  618.     ai    - Optional pointer to the AppInfo structure for this
  619.           application.
  620.     tl    - Optional pointer to an array of TagItems.
  621.  
  622. appshell.library/APSHGetGadgetInfo         appshell.library/APSHGetGadgetInfo
  623.  
  624.    NAME
  625.     APSHGetGadgetInfo - Obtain a pointer to a gadget and its window.
  626.  
  627.    SYNOPSIS
  628.     success = APSHGetGadgetInfo (ai, winname, gadname, winptr, gadptr)
  629.  
  630.     BOOL success;
  631.     struct AppInfo *ai;
  632.     STRPTR winname, gadname;
  633.     ULONG *winptr, *gadptr;
  634.  
  635.    FUNCTION
  636.     Obtain a pointer to a gadget and the window that it belongs in.
  637.  
  638.     Always use this function to get a pointer to a gadget before
  639.     manipulating it.  Never store the gadget or window pointers in your
  640.     UserData for the application.  It is possible that the window is
  641.     closed or been closed since the time you last obtained a gadget
  642.     pointer and are therefore referencing invalid memory locations.
  643.  
  644.     This function is implemented by the IDCMP message handler.
  645.  
  646.    EXAMPLE
  647.  
  648.     /* Sample function showing how to use APSHGetGadgetInfo */
  649.     VOID StubFunc (struct AppInfo * ai, STRPTR cmd, struct TagItem * tl)
  650.     {
  651.         struct Gadget *gad;
  652.         struct Window *win;
  653.  
  654.         /* Get a pointer to the main window, named MAIN, and the Scrolling
  655.          * List gadget, which is named LIST.
  656.          */
  657.         if (APSHGetGadgetInfo (ai, "MAIN", "LIST",
  658.                    (ULONG *)&win, (ULONG *)&gad))
  659.         {
  660.         /* ... do something with the fields ... */
  661.         }
  662.     }
  663.  
  664.  
  665.    INPUTS
  666.     ai    - Pointer to the AppInfo structure
  667.     winname    - Pointer to the name of the window that the gadget is
  668.           supposed to be located in.
  669.     gadname    - Pointer to the name of the gadget.
  670.     winptr    - Address of the variable to place the window pointer in.
  671.     gadptr    - Address of the variable to place the gadget pointer in.
  672.  
  673.    RETURN
  674.     success    - TRUE indicates that the system was able to locate both
  675.           the named window and gadget (and the window is actually
  676.           open).
  677.  
  678.           FALSE indicates that the system was unable to locate
  679.           either the window or the gadget.
  680.  
  681.    BUGS
  682.     This version of the AppShell has stolen the window and gadget
  683.     UserData fields.  Until a method is provided to access per window
  684.     and gadget data, don't use the window->UserData or gadget->UserData.
  685.  
  686. appshell.library/APSHGetWindowInfo         appshell.library/APSHGetWindowInfo
  687.  
  688.    NAME
  689.     APSHGetWindowInfo - Obtain a pointer to a window.
  690.  
  691.    SYNOPSIS
  692.     success = APSHGetWindowInfo (ai, winname, winptr)
  693.  
  694.     BOOL success;
  695.     struct AppInfo *ai;
  696.     STRPTR winname;
  697.     ULONG *winptr;
  698.  
  699.    FUNCTION
  700.     Obtain a pointer to the named window.
  701.  
  702.     Always use this function to get a pointer to a window before
  703.     manipulating it.  Never store the window pointers in the application's
  704.     UserData.  It is possible that the window is closed or been closed
  705.     since the time you last obtained its pointer and are therefore
  706.     referencing invalid memory locations.
  707.  
  708.     This function is implemented by the IDCMP message handler.
  709.  
  710.    EXAMPLE
  711.  
  712.     /* Sample function showing how to use APSHGetWindowInfo */
  713.     VOID StubFunc (struct AppInfo * ai, STRPTR cmd, struct TagItem * tl)
  714.     {
  715.         struct Window *win;
  716.  
  717.         /* Get a pointer to the main window, named MAIN */
  718.         if (APSHGetWindowInfo (ai, "MAIN", (ULONG)&win))
  719.         {
  720.         /* ... do something with the fields ... */
  721.         }
  722.     }
  723.  
  724.  
  725.    INPUTS
  726.     ai    - Pointer to the AppInfo structure
  727.     winname    - Pointer to the name of the window.
  728.     winptr    - Address of the variable to place the window pointer in.
  729.  
  730.    RETURN
  731.     success    - TRUE indicates that the system was able to locate
  732.           the named window and that it was open.
  733.  
  734.           FALSE indicates that the system was unable to locate
  735.           the named window or that it wasn't open.
  736.  
  737.    BUGS
  738.     This version of the AppShell has stolen the window and gadget
  739.     UserData fields.  Until a method is provided to access per window
  740.     and gadget data, don't use the window->UserData or gadget->UserData.
  741.  
  742. appshell.library/APSHSetWaitPointer       appshell.library/APSHSetWaitPointer
  743.  
  744.    NAME
  745.     APSHSetWaitPointer - Display a wait pointer.
  746.  
  747.    SYNOPSIS
  748.     APSHSetWaitPointer (ai, tl);
  749.  
  750.     struct AppInfo * ai;
  751.     struct TagItem * tl;
  752.  
  753.    FUNCTION
  754.     This function displays a wait pointer in the specified window.
  755.     Defaults to the current window (according to AppShell).
  756.  
  757.     Valid TagItems are:
  758.  
  759.         APSH_WinName, <name>
  760.         where <name> is a valid window name.
  761.  
  762.         APSH_WinPointer, <pointer>
  763.         where <pointer> points to a valid window.
  764.  
  765.    INPUTS
  766.     ai    - Optional pointer to the AppInfo structure for this
  767.           application.
  768.     tl    - Optional pointer to an array of TagItems.
  769.  
  770. appshell.library/BuildParseLine               appshell.library/BuildParseLine
  771.  
  772.    NAME
  773.     BuildParseLine - Non-destructive string parser
  774.  
  775.    SYNOPSIS
  776.     handle = BuildParseLine (line, argc, argv);
  777.  
  778.     STRPTR handle;
  779.     STRPTR line;
  780.     ULONG *argc;
  781.     STRPTR argv[MAXARGS];
  782.  
  783.    FUNCTION
  784.     This function is used to parse a string that may end up being
  785.     passed to another function.  It does not modify the passed
  786.     string.  Requires a corresponding call to FreeParseLine, when the
  787.     application's function is done with the parsed line.
  788.  
  789.    INPUTS
  790.     line     - Pointer to the string to parse.
  791.     argc     - Pointer to variable to hold the number of arguments.
  792.     argv     - Pointer to an array to hold the arguments.  The array
  793.            must contain MAXARGS entries.
  794.  
  795.    RETURN
  796.     handle   - Pointer to a temporary work area which must be passed
  797.            back to FreeParseLine when done with the parsed array.
  798.  
  799.    EXAMPLE
  800.  
  801.     /* sample function showing how to use BuildParseLine & FreeParseLine */
  802.     function()
  803.     {
  804.         STRPTR argv[MAXARGS], handle = NULL;
  805.         ULONG argc;
  806.  
  807.         /* Parse the command line */
  808.         handle = BuildParseLine ("ACTIVATE ME", &argc, argv);
  809.  
  810.         /* Do something with the parsed command line.  The strings
  811.          * must be copied before calling FreeParseLine if they are
  812.          * going to be used later.
  813.          */
  814.         printf("%ld words, first is %s\n", argc, argv[0]);
  815.  
  816.         /* free the BuildParseLine resources */
  817.         FreeParseLine(handle);
  818.     }
  819.  
  820.    SEE ALSO
  821.     FreeParseLine(), ParseLine()
  822.  
  823. appshell.library/FindType                           appshell.library/FindType
  824.  
  825.    NAME
  826.     FindType - Find the value of a variable.
  827.  
  828.    SYNOPSIS
  829.     value = FindType(argv, name, defvalue)
  830.  
  831.     STRPTR value;
  832.     STRPTR argv[MAXARGS];
  833.     STRPTR name, defvalue;
  834.  
  835.    FUNCTION
  836.     This function searches a parsed text array for a given entry and
  837.     returns a pointer to the value bound to that entry.  If the entry is
  838.     not found, then a pointer to defvalue is returned.
  839.  
  840.    EXAMPLE
  841.  
  842.     /* sample fragment showing how to use FindType */
  843.     VOID StubFunc (struct AppInfo *ai, STRPTR cmd, struct TagItem *tl)
  844.     {
  845.         STRPTR name;
  846.         STRPTR argv[MAXARG], clone=NULL;
  847.         ULONG argc;
  848.  
  849.         /* make sure we have a command line */
  850.         if (cmd)
  851.         {
  852.         /* parse the command line */
  853.         clone = BuildParseLine (cmd, &argc, argv);
  854.  
  855.         /* Get the file name.  If there isn't a FILE keyword, then
  856.          * use "config".  If the return value is to be used outside
  857.          * of this function, then it must be copied.
  858.          */
  859.         name = FindType (argv, "FILE", "config");
  860.         }
  861.  
  862.         /* free the BuildParseLine */
  863.         FreeParseLine (clone);
  864.     }
  865.  
  866.    INPUTS
  867.     argv     - Pointer to the preparsed text array.
  868.     name     - Entry to search for.
  869.     defvalue - Value to return if name isn't found.
  870.  
  871.    RESULTS
  872.     value     - A pointer to the string that is the value bound to name or
  873.            defvalue if name isn't found.
  874.  
  875.    SEE ALSO
  876.     MatchValue(), BuildParseLine(), FreeParseLine(), ParseLine(),
  877.     icon.library/FindToolType
  878.  
  879. appshell.library/FreeParseLine                 appshell.library/FreeParseLine
  880.  
  881.    NAME
  882.     FreeParseLine - Free the BuildParseLine temporary work area
  883.  
  884.    SYNOPSIS
  885.     FreeParseLine(handle)
  886.  
  887.     STRPTR handle;
  888.  
  889.    FUNCTION
  890.     Free the temporary work space used by BuildParseLine.  A NULL is a
  891.     valid argument.
  892.  
  893.    INPUTS
  894.     handle   - Pointer to the return value from BuildParseLine.
  895.  
  896.    SEE ALSO
  897.     BuildParseLine(), ParseLine()
  898.  
  899. appshell.library/FreeProject                     appshell.library/FreeProject
  900.  
  901.    NAME
  902.     FreeProject - Removes and deallocate a project from the project list.
  903.  
  904.    SYNOPSIS
  905.     FreeProject (proj);
  906.  
  907.     struct ProjNode *proj;
  908.  
  909.    FUNCTION
  910.     Removes and deallocates a project node from the project list.
  911.  
  912.    INPUTS
  913.     proj    - Pointer to a valid ProjNode structure.
  914.  
  915. appshell.library/FreeProjects                   appshell.library/FreeProjects
  916.  
  917.    NAME
  918.     FreeProjects - Remove and deallocate all the projects in a project list.
  919.  
  920.    SYNOPSIS
  921.     FreeProjects (ai, tl);
  922.  
  923.     struct AppInfo *ai;
  924.     struct TagItem *tl;
  925.  
  926.    FUNCTION
  927.     Removes and deallocate all the projects in a project list.  Defaults
  928.     to the main project list.
  929.  
  930.     Valid TagItems are:
  931.  
  932.         APSH_ProjInfo,<project>
  933.         Where <project> is a valid pointer to a Project structure.
  934.         Defaults to the AppInfo project structure.
  935.  
  936.    INPUTS
  937.     ai    - Pointer to the application AppInfo structure.
  938.     tl    - Pointer to an optional TagItem array.
  939.  
  940. appshell.library/GetFuncEntry                   appshell.library/GetFuncEntry
  941.  
  942.    NAME
  943.     GetFuncEntry - Get a pointer to a function table entry.
  944.  
  945.    SYNOPSIS
  946.     entry = GetFuncEntry (ai, cmd, fid);
  947.  
  948.     struct FuncEntry *entry;
  949.     struct AppInfo *ai;
  950.     STRPTR cmd;
  951.     ULONG fid;
  952.  
  953.    FUNCTION
  954.     This function is used to obtain a pointer to a function table entry.
  955.  
  956.     Currently the FuncEntry structure is private.
  957.  
  958.    INPUTS
  959.     ai    - Pointer to the application's AppInfo structure.
  960.     cmd    - Pointer to the command name to locate.  Either cmd or fid
  961.           must be provided.
  962.     fid    - Command ID of the command to locate.
  963.  
  964.    RESULT
  965.     entry    - Pointer to a FuncEntry structure that describes the command.
  966.  
  967.    SEE ALSO
  968.     GetFuncID(), GetFuncName()
  969.  
  970. appshell.library/GetFuncID                         appshell.library/GetFuncID
  971.  
  972.    NAME
  973.     GetFuncID - Given a command name, return the ID for the function.
  974.  
  975.    SYNOPSIS
  976.     fid = GetFuncID (ai, cmd);
  977.  
  978.     ULONG fid;
  979.     struct AppInfo *ai;
  980.     STRPTR cmd;
  981.  
  982.    FUNCTION
  983.     This function will return the command ID for the function.
  984.  
  985.    INPUTS
  986.     ai    - Pointer to the application's AppInfo structure.
  987.     cmd    - Pointer to the command name to locate.
  988.  
  989.    RESULT
  990.     fid    - Command ID of the function.
  991.  
  992.    SEE ALSO
  993.     GetFuncEntry(), GetFuncName()
  994.  
  995. appshell.library/GetFuncName                     appshell.library/GetFuncName
  996.  
  997.    NAME
  998.     GetFuncName - Given a command ID, return the name of the function.
  999.  
  1000.    SYNOPSIS
  1001.     cmd = GetFuncName (ai, fid);
  1002.  
  1003.     STRPTR cmd;
  1004.     struct AppInfo *ai;
  1005.     ULONG fid;
  1006.  
  1007.    FUNCTION
  1008.     This function will return the name of the function for the given
  1009.     command ID.
  1010.  
  1011.    INPUTS
  1012.     ai    - Pointer to the application's AppInfo structure.
  1013.     fid    - Command ID of the function.
  1014.  
  1015.    RESULT
  1016.     cmd    - Pointer to the command name.
  1017.  
  1018.    SEE ALSO
  1019.     GetFuncEntry(), GetFuncID()
  1020.  
  1021. appshell.library/GetProjNode                     appshell.library/GetProjNode
  1022.  
  1023.    NAME
  1024.     GetProjNode - Get the requested project node.
  1025.  
  1026.    SYNOPSIS
  1027.     proj = GetProjNode (ai, id, tl);
  1028.  
  1029.     struct ProjNode *proj;
  1030.     struct AppInfo *ai;
  1031.     LONG id;
  1032.     struct TagItem *tl;
  1033.  
  1034.    FUNCTION
  1035.     Given a project ID, find the correct ProjNode.
  1036.  
  1037.     Valid TagItems are:
  1038.  
  1039.         APSH_ProjInfo,<project>
  1040.         Where <project> is a valid pointer to a Project structure.
  1041.         Defaults to the AppInfo project structure.
  1042.  
  1043.    INPUTS
  1044.     ai    - Pointer to the application AppInfo structure.
  1045.     id    - Project ID to locate.
  1046.     tl    - Pointer to an optional TagItem array.
  1047.  
  1048. appshell.library/GetText                             appshell.library/GetText
  1049.  
  1050.    NAME
  1051.     GetText - Obtain a pointer to a permanent read-only text message.
  1052.  
  1053.    SYNOPSIS
  1054.     text = GetText(ai, base, id, def)
  1055.  
  1056.     STRPTR text;
  1057.     struct AppInfo *ai;
  1058.     ULONG base, id;
  1059.     STRPTR def;
  1060.  
  1061.    FUNCTION
  1062.     Used to obtain a pointer to a permanent text message.  The text
  1063.     return value must not be modified.
  1064.  
  1065.     The main use for this function is for setting up text labels.
  1066.  
  1067.    EXAMPLE
  1068.  
  1069.     /* sample function to show how to use GetText */
  1070.     VOID StubFunc (struct AppInfo *ai, STRPTR cmd, struct TagItem *tl)
  1071.     {
  1072.         STRPTR label;
  1073.  
  1074.         /* get the current text to use for Okay */
  1075.         label = GetText (ai, APSH_MAIN_ID, APSH_OKAY_TXT, NULL);
  1076.     }
  1077.  
  1078.    INPUTS
  1079.     ai    - Pointer to the AppInfo structure for this application.
  1080.     base    - Text table to use.
  1081.  
  1082.           APSH_USER_ID for the application text table.
  1083.           APSH_MAIN_ID for the AppShell text table.
  1084.           or may provide a custom message handler base ID.
  1085.  
  1086.     id    - Text Table entry id.
  1087.     def    - Must be NULL.
  1088.  
  1089.    SEE ALSO
  1090.     PrepText()
  1091.  
  1092. appshell.library/HandleAppAsync               appshell.library/HandleAppAsync
  1093.  
  1094.    NAME
  1095.     HandleAppAsync - startup function for an asynchronous AppShell
  1096.     application.
  1097.  
  1098.    SYNOPSIS
  1099.     results = HandleAppAsync (attrs, sipc)
  1100.  
  1101.     BOOL results;
  1102.     struct TagItem *attrs;
  1103.     struct MsgPort *sipc;
  1104.  
  1105.    FUNCTION
  1106.     This function is the application entry point for an asynchronous
  1107.     AppShell application.  This function should be called via the
  1108.     Tool Message Handler and allows an AppShell application to have
  1109.     multiple projects each with their own process.
  1110.  
  1111.    EXAMPLE
  1112.  
  1113.     /* This example shows how an application can clone itself to handle
  1114.      * multiple projects.
  1115.      *
  1116.      * APSH_Tool      the name to give to the cloned process.
  1117.      * APSH_ToolAddr  the function to run ansynchronously.
  1118.      * APSH_ToolData  the user interface tag description.
  1119.      */
  1120.     VOID CloneFunc(struct AppInfo *ai, STRPTR args, struct TagItem *tl)
  1121.     {
  1122.         HandlerFunc (ai,
  1123.              APSH_Handler,   "TOOL",
  1124.              APSH_Command,   MH_OPEN,
  1125.              APSH_Tool,      "AppShell_Clone",
  1126.              APSH_ToolAddr,  HandleAppAsync,
  1127.              APSH_ToolData,  Cloned_App,
  1128.              TAG_DONE);
  1129.     }
  1130.  
  1131.    INPUTS
  1132.     attrs    - Pointer to the application's user interface
  1133.           description.
  1134.  
  1135.     sipc    - SIPC message port by which the master application
  1136.           can control the cloned application.
  1137.  
  1138.    RESULT
  1139.     TRUE    - Application was able to initialize and run.
  1140.  
  1141.     FALSE    - Application failed.  AppShell has already informed
  1142.           user of what and where the failure was.
  1143.  
  1144.    SEE ALSO
  1145.     HandleApp()
  1146.  
  1147. appshell.library/HandlerData                     appshell.library/HandlerData
  1148.  
  1149.    NAME
  1150.     HandlerData - Obtain a pointer to a message handlers' instance data
  1151.  
  1152.    SYNOPSIS
  1153.     ap = HandlerData (struct AppInfo *ai, ULONG tags, ...)
  1154.  
  1155.     APTR ap;
  1156.     struct AppInfo *ai;
  1157.     ULONG tags, ...
  1158.  
  1159.        OR
  1160.  
  1161.     ap = HandlerDataA (struct AppInfo *ai, struct TagItem *tl)
  1162.  
  1163.     APTR ap;
  1164.     struct AppInfo *ai;
  1165.     struct TagItem *tl;
  1166.  
  1167.    FUNCTION
  1168.     Used to obtain a pointer to a message handlers' instance data.
  1169.     HandlerData is the stack-based variable argument interface, while
  1170.     HandlerDataA is the TagItem array interface.
  1171.  
  1172.    EXAMPLE
  1173.  
  1174.     /* sample stub function to show how to obtain a message handlers'
  1175.      * data
  1176.      */
  1177.     VOID StubFunc(struct AppInfo *ai, STRPTR cmd, struct TagItem *tl)
  1178.     {
  1179.         struct MsgHandler *mh;
  1180.         struct MHObject *mho;
  1181.         struct myhInfo *md;
  1182.  
  1183.         /* get a pointer to the message handler data */
  1184.         if (mho = (struct MHObject *)
  1185.         HandlerData(ai,APSH_Handler,"MYH",TAG_DONE))
  1186.         {
  1187.         /* get a pointer to the instance data */
  1188.         md = mho->mho_SysData;
  1189.         }
  1190.     }
  1191.  
  1192.    INPUTS
  1193.     ai    - pointer to the AppInfo structure for this application.
  1194.     tags    - stack based TagItems.
  1195.  
  1196.    RESULTS
  1197.     ap    - Pointer to the message handler instance data.
  1198.  
  1199.    SEE ALSO
  1200.     HandlerFunc()
  1201.  
  1202. appshell.library/HandlerFunc                     appshell.library/HandlerFunc
  1203.  
  1204.    NAME
  1205.     HandlerFunc - entry point for a low-level message handler function.
  1206.  
  1207.    SYNOPSIS
  1208.     HandlerFunc (struct AppInfo *ai, ULONG tags, ...)
  1209.  
  1210.     struct AppInfo *ai;
  1211.     ULONG tags, ...
  1212.  
  1213.        OR
  1214.  
  1215.     HandlerFuncA (struct AppInfo *ai, struct TagItem *tl)
  1216.  
  1217.     struct AppInfo *ai;
  1218.     struct TagItem *tl;
  1219.  
  1220.    FUNCTION
  1221.     Provides an entry point for the low-level message handler functions.
  1222.     HandlerFunc is the stack-based variable argument interface, while
  1223.     HandlerFuncA is the TagItem array interface.
  1224.  
  1225.    EXAMPLE
  1226.  
  1227.     /* sample stub function to show how to call a low-level message
  1228.      * handler function.
  1229.      *
  1230.      * This example tells the IDCMP message handler to open the window
  1231.      * (and it's environment) named MAIN.
  1232.      */
  1233.     VOID StubFunc(struct AppInfo *ai, STRPTR cmd, struct TagItem *tl)
  1234.     {
  1235.         HandlerFunc(ai,
  1236.             APSH_Handler, "IDCMP",
  1237.             APSH_Command, MH_OPEN,
  1238.             APSH_NameTag, "MAIN",
  1239.             TAG_DONE);
  1240.     }
  1241.  
  1242.    INPUTS
  1243.     ai    - pointer to the AppInfo structure for this application.
  1244.     tags    - stack based TagItems.
  1245.  
  1246.    SEE ALSO
  1247.     HandlerData()
  1248.  
  1249. appshell.library/IconFromWBArg                 appshell.library/IconFromWBArg
  1250.  
  1251.    NAME
  1252.     IconFromWBArg - Obtains the icon for a Workbench argument.
  1253.  
  1254.    SYNOPSIS
  1255.     dob = IconFromWBArg (wbarg);
  1256.  
  1257.     struct DiskObject *dob;
  1258.     struct WBArg *wbarg;
  1259.  
  1260.    FUNCTION
  1261.     Given a valid Workbench argument, this command will return the
  1262.     proper icon.  This call uses the new (V36) GetDiskObjectNew call
  1263.     to ensure that an icon will be returned.
  1264.  
  1265.    INPUTS
  1266.     wbarg    - Pointer to a filled in WBArg structure.
  1267.  
  1268.    RESULTS
  1269.     dob    - Pointer to a DiskObject structure.  Application must call
  1270.           FreeDiskObject when done with the icon.
  1271.  
  1272. appshell.library/MatchValue                       appshell.library/MatchValue
  1273.  
  1274.    NAME
  1275.     MatchValue - Check a text argument for a particular flag.
  1276.  
  1277.    SYNOPSIS
  1278.     value = MatchValue(entry, value)
  1279.  
  1280.     BOOL value;
  1281.     STRPTR entry, value;
  1282.  
  1283.    FUNCTION
  1284.     This function searchs to see if a particular text flag is set in
  1285.     a text entry.
  1286.  
  1287.    EXAMPLE
  1288.  
  1289.     /* sample fragment showing how to use MatchValue */
  1290.     VOID StubFunc (struct AppInfo *ai, STRPTR cmd, struct TagItem *tl)
  1291.     {
  1292.         STRPTR flagstr;
  1293.         ULONG flags = NULL;
  1294.         STRPTR argv[MAXARG], clone=NULL;
  1295.         ULONG argc;
  1296.  
  1297.         /* make sure we have a command line */
  1298.         if (cmd)
  1299.         {
  1300.         /* parse the command line */
  1301.         clone = BuildParseLine (cmd, &argc, argv);
  1302.  
  1303.         /* get the flag entry from the argument list */
  1304.         if (flagstr = FindType (argv, "FLAGS", NULL))
  1305.         {
  1306.             /* see if the CLOSE flag is present */
  1307.             if (MatchValue (flagstr, "CLOSE"))
  1308.             flags |= CLOSEWINDOW;
  1309.  
  1310.             /* see if the SIZE flag is present */
  1311.             if (MatchValue (flagstr, "SIZE"))
  1312.             flags |= NEWSIZE;
  1313.         }
  1314.         }
  1315.  
  1316.         /* free the BuildParseLine */
  1317.         FreeParseLine (clone);
  1318.     }
  1319.  
  1320.    INPUTS
  1321.     entry     - Entry to search in.
  1322.     value     - Value to search for.
  1323.  
  1324.    RESULTS
  1325.     value     - TRUE if the value was in the entry, otherwise returns
  1326.            FALSE.
  1327.  
  1328.    SEE ALSO
  1329.     FindType(), BuildParseLine(), FreeParseLine(), ParseLine(),
  1330.     icon.library/MatchToolValue
  1331.  
  1332. appshell.library/NewProject                       appshell.library/NewProject
  1333.  
  1334.    NAME
  1335.     NewProject - Create a project node and add it to the project list.
  1336.  
  1337.    SYNOPSIS
  1338.     proj = NewProject (ai, name, tl);
  1339.  
  1340.     struct ProjNode *proj;
  1341.     struct AppInfo *ai;
  1342.     STRPTR name;
  1343.     struct TagItem *tl;
  1344.  
  1345.    FUNCTION
  1346.     Creates a project node of the given name and adds it to the requested
  1347.     project list.  The project list defaults to the main project list.
  1348.     If the name is NULL, the function will determine the name by finding
  1349.     the next available Unnamed slot.
  1350.  
  1351.     Valid TagItems are:
  1352.  
  1353.         APSH_ProjInfo, <project>
  1354.         Where <project> is a valid pointer to a Project structure.
  1355.         Defaults to the AppInfo project structure.
  1356.  
  1357.         APSH_NameTag, <name>
  1358.         Where <name> is the name to be added to the project list.
  1359.  
  1360.         APSH_TextID, <text ID>
  1361.         Where <text ID> is the text ID from the applications text
  1362.         table to use for the prefix when a name isn't given.  Defaults
  1363.         to Unnamed from the AppShell text table.  The resulting
  1364.         prefix will be truncated to twenty characters.
  1365.  
  1366.         APSH_BaseID, <base ID>
  1367.         Where <base ID> is the text table to use when APSH_TextID is
  1368.         supplied.  Defaults to APSH_USER_ID.
  1369.  
  1370.    INPUTS
  1371.     ai    - Pointer to the application AppInfo structure.
  1372.     name    - Pointer to the name to give to the project.
  1373.     tl    - Pointer to an optional TagItem array.
  1374.  
  1375.    RESULT
  1376.     proj    - Pointer to a filled in ProjNode structure
  1377.  
  1378. appshell.library/ParseLine                         appshell.library/ParseLine
  1379.  
  1380.    NAME
  1381.     ParseLine - Destructive string parser
  1382.  
  1383.    SYNOPSIS
  1384.     argc = ParseLine (line, argv);
  1385.  
  1386.     ULONG argc;
  1387.     STRPTR line;
  1388.     STRPTR argv[MAXARGS];
  1389.  
  1390.    FUNCTION
  1391.     String parser.  Inserts '\0' after each word in the passed text
  1392.     line.
  1393.  
  1394.    INPUTS
  1395.     line     - Pointer to the string to parse.
  1396.     argv     - Pointer to an array to hold the arguments.  The array
  1397.            must contain MAXARGS entries.
  1398.  
  1399.    RETURN
  1400.     argc     - Number of arguments returned in argv
  1401.  
  1402.    EXAMPLE
  1403.  
  1404.     /* sample function showing how to use ParseLine */
  1405.     VOID StubFunc (struct AppInfo *ai, STRPTR cmd, struct TagItem *tl)
  1406.     {
  1407.         UBYTE text[] = "ACTIVATE ME";
  1408.         STRPTR argv[MAXARGS];
  1409.         ULONG argc;
  1410.  
  1411.         /* parse the command line */
  1412.         argc = ParseLine (text, argv);
  1413.  
  1414.         /* simple display of some of the parse variables */
  1415.         printf("%ld words, first is %s\n", argc, argv[0]);
  1416.     }
  1417.  
  1418.    SEE ALSO
  1419.     BuildParseLine(), FreeParseLine()
  1420.  
  1421. appshell.library/PerfFunc                           appshell.library/PerfFunc
  1422.  
  1423.    NAME
  1424.     PerfFunc - The entry point to all commands in the function table.
  1425.  
  1426.    SYNOPSIS
  1427.     PerfFunc (ai, fid, cmdline, attrs)
  1428.  
  1429.     struct AppInfo *ai;
  1430.     ULONG fid;
  1431.     STRPTR cmdline;
  1432.     struct TagItem *attrs;
  1433.  
  1434.    FUNCTION
  1435.     This is the main and only entry point for all commands in the
  1436.     function table.  In order to respect state, such as whether the
  1437.     function is enabled or disabled, function table commands should
  1438.     never be called directly.
  1439.  
  1440.     If the function isn't in the function table and the ARexx message
  1441.     handler has been initialized, then the command is passed to ARexx.
  1442.  
  1443.    EXAMPLE
  1444.  
  1445.     /* how to call a function using its ID */
  1446.     PerfFunc (ai, QuitID, NULL, NULL);
  1447.  
  1448.     /* how to call a function using its name */
  1449.     PerfFunc (ai, NULL, "QUIT", NULL);
  1450.  
  1451.  
  1452.    INPUTS
  1453.     ai    - Pointer to the AppInfo structure
  1454.     fid    - ID of function to perform.
  1455.     cmdline    - Pointer to the text command line to use to trigger the
  1456.           command.
  1457.     attrs    - Pointer to the TagItem array to use to triggered the
  1458.           command.
  1459.  
  1460. appshell.library/PrepText                           appshell.library/PrepText
  1461.  
  1462.    NAME
  1463.     PrepText - Obtain a pointer to a temporary modifiable text message.
  1464.  
  1465.    SYNOPSIS
  1466.     text = PrepText(ai, base, id, args, ...)
  1467.  
  1468.     STRPTR text;
  1469.     struct AppInfo *ai;
  1470.     ULONG base, id;
  1471.     APTR args;
  1472.  
  1473.    FUNCTION
  1474.     Build a temporary text message using a text table entry and the
  1475.     passed arguments.  The text table entry must contain valid
  1476.     RawDoFmt formatting commands.
  1477.  
  1478.     The text pointer is only valid until the next call to PrepText.
  1479.     There is one PrepText buffer per AppInfo, so each cloned AppShell
  1480.     has its own work buffer.  The string must be copied to a more
  1481.     permanent storage place if you wish to keep it for a longer period.
  1482.  
  1483.     The main use for this function is for formatting of temporary
  1484.     error messages.
  1485.  
  1486.    EXAMPLE
  1487.  
  1488.     /* set up error return values */
  1489.     ai->ai_Pri_Ret = RETURN_FAIL;
  1490.     ai->ai_Sec_Ret = APSH_PORT_ACTIVE;
  1491.  
  1492.     /* "%s port already active", pname */
  1493.     ai->ai_TextRtn = PrepText(ai, APSH_MAIN_ID, ai->ai_Sec_Ret, pname);
  1494.  
  1495.  
  1496.    INPUTS
  1497.     ai    - Pointer to the AppInfo structure for this application.
  1498.     base    - Text table to use.
  1499.  
  1500.           APSH_USER_ID for the application text table.
  1501.           APSH_MAIN_ID for the AppShell text table.
  1502.           or may provide a custom message handler base ID.
  1503.  
  1504.     id    - Text Table entry id.
  1505.     args    - Variables to be sprintf'ed into the text entry.
  1506.  
  1507.    SEE ALSO
  1508.     GetText()
  1509.  
  1510. appshell.library/QStrCmpI                           appshell.library/QStrCmpI
  1511.  
  1512.    NAME
  1513.     QStrCmpI - Quick case insensitive string comparision.
  1514.  
  1515.    SYNOPSIS
  1516.     success = QStrCmpI (str1, str2);
  1517.  
  1518.     BOOL value;
  1519.     STRPTR str1, str2;
  1520.  
  1521.    FUNCTION
  1522.     This function performs a quick, case insensitive, string comparision.
  1523.     Stops as soon as it determines that the strings are not the same.
  1524.  
  1525.    EXAMPLE
  1526.  
  1527.     /* sample code fragment showing how to use QStrCmpI */
  1528.     VOID StubFunc (struct AppInfo *ai, STRPTR cmd, struct TagItem *tl)
  1529.     {
  1530.         STRPTR name;
  1531.         STRPTR argv[MAXARG], clone=NULL;
  1532.         ULONG argc;
  1533.  
  1534.         /* make sure we have a command line */
  1535.         if (cmd)
  1536.         {
  1537.         /* parse the command line */
  1538.         clone = BuildParseLine (cmd, &argc, argv);
  1539.  
  1540.         /* make sure we have some arguments */
  1541.         if (argc >= 2L)
  1542.         {
  1543.             /* check to see if the first argument is CLOSE.
  1544.              * Note that FindType(argv, "CLOSE", NULL) could also be
  1545.              * used in this example.
  1546.              */
  1547.             if (QStrCmpI (argv[1], "CLOSE"))
  1548.             {
  1549.             /* do something because of CLOSE */
  1550.             }
  1551.         }
  1552.         }
  1553.  
  1554.         /* free the BuildParseLine */
  1555.         FreeParseLine (clone);
  1556.     }
  1557.  
  1558.    INPUTS
  1559.     str1     - Pointer to the first string.
  1560.     str2     - Pointer to the second string.
  1561.  
  1562.    RESULTS
  1563.     value     - TRUE if the strings are the same, otherwise returns FALSE.
  1564.  
  1565. appshell.library/RemoveMsgPort                 appshell.library/RemoveMsgPort
  1566.  
  1567.    NAME
  1568.     RemoveMsgPort - Safely remove a message port.
  1569.  
  1570.    SYNOPSIS
  1571.     RemoveMsgPort (mp);
  1572.  
  1573.     struct MsgPort *mp;
  1574.  
  1575.    FUNCTION
  1576.     This function will remove and reply to all messages that are
  1577.     outstanding on a message port before removing the port itself.
  1578.  
  1579.     NULL is a valid argument.
  1580.  
  1581.    INPUTS
  1582.     mp    - A pointer to the message port to delete.
  1583.  
  1584. appshell.library/RemoveProject                 appshell.library/RemoveProject
  1585.  
  1586.    NAME
  1587.     RemoveProject - Remove a project node from the project list.
  1588.  
  1589.    SYNOPSIS
  1590.     BOOL RemoveProject (ai, name, tl);
  1591.  
  1592.     struct AppInfo *ai;
  1593.     STRPTR name;
  1594.     struct TagItem *tl;
  1595.  
  1596.    FUNCTION
  1597.     Removes a project node of the given name from the requested project
  1598.     list.  Defaults to removing the current project node from the main
  1599.     project list.  
  1600.  
  1601.     Valid TagItems are:
  1602.  
  1603.         APSH_ProjInfo, <project>
  1604.         Where <project> is a valid pointer to a Project structure.
  1605.         Defaults to the AppInfo project structure.
  1606.  
  1607.         APSH_NameTag, <name>
  1608.         Where <name> is a valid project name to be removed.
  1609.  
  1610.    INPUTS
  1611.     ai    - Pointer to the application AppInfo structure.
  1612.     name    - Pointer to the name of the project to be removed.
  1613.     tl    - Pointer to an optional TagItem array.
  1614.  
  1615.    RESULT
  1616.     TRUE    - Able to remove the project from the list.
  1617.     FALSE    - Unable to remove the project.
  1618. appshell.library/SwapProjNodes                 appshell.library/SwapProjNodes
  1619.  
  1620.    NAME
  1621.     SwapProjNodes - Swap two project nodes within the same Project list.
  1622.  
  1623.    SYNOPSIS
  1624.     SwapProjNodes (ai, pn1, pn2, tl);
  1625.  
  1626.     struct AppInfo *ai;
  1627.     struct ProjNode *pn1;
  1628.     struct ProjNode *pn2;
  1629.     struct TagItem *tl;
  1630.  
  1631.    FUNCTION
  1632.     This function will swap two project nodes within the same project
  1633.     list.
  1634.  
  1635.     Valid TagItems are:
  1636.  
  1637.         APSH_ProjInfo,<project>
  1638.         Where <project> is a valid pointer to a Project structure.
  1639.         Defaults to the AppInfo project structure.
  1640.  
  1641.    INPUTS
  1642.     ai    - Pointer to the application AppInfo structure.
  1643.     pn1    - Pointer to a valid ProjNode structure.
  1644.     pn2    - Pointer to a valid ProjNode structure.
  1645.     tl    - Pointer to an optional TagItem array.
  1646.  
  1647.